/*
 * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package jdk.io;

import java.io.IOException;

/**
 * 数据输出接口用于将数据从任何 Java 基本类型转换为一系列字节，并将这些字节写入二进制流。
 * 还有一个方法可以将 {@code String} 转换为修改版 UTF-8 格式并写出结果字节序列。
 *
 * <p>对于此接口中所有写入字节的方法，如果由于任何原因无法写入字节，将抛出
 * {@code IOException}。
 *
 * @author  Frank Yellin
 * @see     java.io.DataInput
 * @see     java.io.DataOutputStream
 * @since   JDK1.0
 */
public interface DataOutput {
    /**
     * 将 {@code b.length} 字节从指定字节数组写入输出流。
     * 如果 {@code b} 为 null，则抛出 {@code NullPointerException}。
     * 如果 {@code b.length} 为 0，则不写入任何字节。否则，字节 {@code b[0]} 到
     * {@code b[b.length-1]} 按顺序写入输出流。
     *
     * @param      b   要写入的数据。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void write(int b) throws IOException;

    /**
     * 将 {@code b.length} 字节从指定字节数组写入输出流。
     * 如果 {@code b} 为 null，则抛出 {@code NullPointerException}。
     * 如果 {@code b.length} 为 0，则不写入任何字节。否则，字节 {@code b[0]} 到
     * {@code b[b.length-1]} 按顺序写入输出流。
     *
     * @param      b   要写入的数据。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void write(byte b[]) throws IOException;

    /**
     * 从指定的字节数组写入 {@code len} 字节，从偏移量 {@code off} 开始。
     * 如果 {@code b} 为 null，则抛出 {@code NullPointerException}。
     * 如果 {@code off} 为负，或 {@code len} 为负，或 {@code off+len} 大于
     * {@code b.length}，则抛出 {@code IndexOutOfBoundsException}。
     * 如果 {@code len} 为 0，则不写入任何字节。否则，字节 {@code b[off]} 到
     * {@code b[off+len-1]} 按顺序写入输出流。
     *
     * @param      b     要写入的数据。
     * @param      off   数据中的起始偏移量。
     * @param      len   要写入的字节数。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void write(byte b[], int off, int len) throws IOException;

    /**
     * 写入布尔值作为 1 字节值。值 {@code true} 写出为值 {@code (byte)1}；
     * 值 {@code false} 写出为值 {@code (byte)0}。
     *
     * @param      v   要写入的布尔值。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeBoolean(boolean v) throws IOException;

    /**
     * 将 {@code byte} 作为 1 字节值写出。
     *
     * @param      v   要写入的 {@code byte} 值。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeByte(int v) throws IOException;

    /**
     * 将 {@code short} 作为 2 字节值，高字节在前。
     *
     * @param      v   要写入的 {@code short} 值。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeShort(int v) throws IOException;

    /**
     * 将 {@code char} 作为 2 字节值，高字节在前。
     *
     * @param      v   要写入的 {@code char} 值。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeChar(int v) throws IOException;

    /**
     * 将 {@code int} 作为 4 字节值，高字节在前。
     *
     * @param      v   要写入的 {@code int} 值。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeInt(int v) throws IOException;

    /**
     * 将 {@code long} 作为 8 字节值，高字节在前。
     *
     * @param      v   要写入的 {@code long} 值。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeLong(long v) throws IOException;

    /**
     * 将 {@code float} 作为 4 字节值，高字节在前。
     *
     * @param      v   要写入的 {@code float} 值。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeFloat(float v) throws IOException;

    /**
     * 将 {@code double} 作为 8 字节值，高字节在前。
     *
     * @param      v   要写入的 {@code double} 值。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeDouble(double v) throws IOException;

    /**
     * 将字符串写入输出流。对于字符串中的每个字符，将写出低 8 位。
     * 如果 {@code s} 为 null，则抛出 {@code NullPointerException}。
     * 如果 {@code s.length} 为 0，则不写入任何字节。否则，字符 {@code s[0]} 到
     * {@code s[s.length-1]} 按顺序写入输出流。
     *
     * @param      s   要写入的 {@code String}。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeBytes(String s) throws IOException;

    /**
     * 将字符串写入输出流。对于字符串中的每个字符，将写出 2 字节，高字节在前。
     * 如果 {@code s} 为 null，则抛出 {@code NullPointerException}。
     * 如果 {@code s.length} 为 0，则不写入任何字节。否则，字符 {@code s[0]} 到
     * {@code s[s.length-1]} 按顺序写入输出流。
     *
     * @param      s   要写入的 {@code String}。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeChars(String s) throws IOException;

    /**
     * 使用修改版 UTF-8 编码以机器无关的方式将字符串写入输出流。
     * <p>
     * 首先，通过 {@code writeShort} 方法将两个字节写入输出流，以与字节序列长度相同的顺序，
     * 以给出要遵循的字节数。此值是实际写入输出流的字节数，而不是字符串的长度。
     * 根据字符串 {@code s} 中的字符序列，使用修改版 UTF-8 编码写出字符序列。
     * 每个字符在字符串中由 1、2 或 3 字节组成。
     *
     * @param      str   要写入的 {@code String}。
     * @exception  IOException  如果发生 I/O 错误。
     */
    void writeUTF(String str) throws IOException;
}
